ButtonSprite is a hack I put together and while the code isnt pretty - it is fast and easy to setup. Some features I plan on adding (which may slightly change the api) are accelerator keys, toggleable buttons and to allow non-rectangular button hittesting.
Of course the fastest way to learn how to use ButtonSprites is to look through the demo code. I added some buttons to Vern's breakout game. Also try holding down the command key and dragging the buttons around - which is my ResEdit substitute. You have to save the location of the buttons to a file yourself.
I hope you find ButtonSprite a useful addition to your SpriteWorld projects,
Matthew
*******
Welcome to ButtonSprite. ButtonSprite is a fast way to add functional animated buttons to your SpriteWorld. They are actually sprites and so they obey all the normal rules for sprites and run along with your SpriteWorld animation.
Button Sprites are stored in a ButtonSpriteRec struct which is really just and extension of a SpriteRec struct.
You can type cast to make a ButtonSpriteRec or a ButtonSpritePtr into a SpriteRec or SpritePtr. So you would set the location of a ButtonSprite using the normal routine for setting a regular sprite's location:
So to start with you use all the standard SpriteWorld routines to create and set up your ButtonSprite characteristics such as its location, its visibility, what layer it is in, etc...
But ButtonSprites are obviously different than regular sprites. First of all, they have 4 basic states.
ButtonUp:
The button is active.
ButtonMouseOver:
The button is active and the mouse has passed over it, but it has not been clicked on. While this isnt usually a mac gui thing - soemtimes developers like to highlight buttons as the mouse passes over them. This might be especially useful for game gui elements which may not always look like standard gui elements. This gives more feedback to the user as to what on the screen are active controls.
ButtonDown:
The button is being clicked on and should be highlighted in some way.
ButtonDisabled:
The button is disabled and cannot be clicked on and should be dimmed.
So typically you would create a sprite with frames that represent each of these states. Next you have to register your ButtonSprite with ButtonProcPtr callbacks for each state which is defined as:
SW_FUNC void MyButtonProc(ButtonSpritePtr srcButtonP, int ButtonStateChanged)
ButtonStateChanged is true when your button initially changes state. You will need to set up a ButtonProc for all four states - and I did it this way even though it is a little more work because many developers dont want to just have a single frame for each button state - but maybe completely different animations. In your ButtonMouseOverProc when ButtonStateChanged is true you might want to play a sound effect or maybe an actual clicking sound when the button is pushed. You could have a button which looked like an eyeball that follows your cursor around and blinks when it is clicked on for instance.
You will also need to register an ActionProc (which is just defined as a MoveProc). This is called when someone clicks on your button.
You register your ButtonProcs and your ActionProc for your ButtonSprites with SetUpButtonCallbacks which is defined as:
Then to either activate or disable (make dimmed) a ButtonSprite you can call EnableButton which is defined as:
void EnableButton(ButtonSpritePtr ButtonSprite, int IsButtonEnabled);
Then you need to set up a SetButtonCursorProc. This is called so you can have your cursor act differently if it is over a button. You could change it from an arrow cursor to a finger cursor for instance. It is defined as:
CursorIsInAButton is true if the cursor is currently in a button. You register this when you initialize ButtonSpriteWorld at the beginning of your program with the function:
Then the last step is once per frame (and *only* once per frame and no more) to call UpdateButtonData()
Also ButtonSprite gives you the ability to drag your buttons around. Its not quite ResEdit - but it will do! If you hold down the command key then you can drag the buttons around with your cursor. Of course you will need to write code to save the new button location so it will be remembered the next time you start the application. You prbably will want to turn this feature off when you make your final compile so your end users cant go draggin the controls around. You can control this from changing a #define in 'ButtonSprite.c'
#define kAreControlsDraggable true
You can also create a 'grid' that your controls stick to when you drag them using the cmd key.
